<div id="Tracking-sources"></div>
<div class="header">
<p>
Next: [[cvs: How your build system interacts with CVS#How your build system interacts with CVS|Builds]], Previous: [[cvs: Keyword substitution#Keyword substitution|Keyword substitution]], Up: [[cvs#Top|Top]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Tracking-third_002dparty-sources"></div>
== Tracking third-party sources ==
<div id="index-Third_002dparty-sources"></div>
<div id="index-Tracking-sources"></div>

If you modify a program to better fit your site, you
probably want to include your modifications when the next
release of the program arrives.  <small>CVS</small> can help you with
this task.

<div id="index-Vendor"></div>
<div id="index-Vendor-branch"></div>
<div id="index-Branch_002c-vendor_002d"></div>
In the terminology used in <small>CVS</small>, the supplier of the
program is called a <em>vendor</em>.  The unmodified
distribution from the vendor is checked in on its own
branch, the <em>vendor branch</em>.  <small>CVS</small> reserves branch
1.1.1 for this use.

When you modify the source and commit it, your revision
will end up on the main trunk.  When a new release is
made by the vendor, you commit it on the vendor branch
and copy the modifications onto the main trunk.

Use the <code>import</code> command to create and update
the vendor branch.  When you import a new file,
the vendor branch is made the &lsquo;head&rsquo; revision, so
anyone that checks out a copy of the file gets that
revision.  When a local modification is committed it is
placed on the main trunk, and made the &lsquo;head&rsquo;
revision.

<div class="menu-preformatted" style="font-family: serif">
 [[#Importing for the first time|&bull; First import]]::                Importing for the first time
 [[#Updating with the import command|&bull; Update imports]]::              Updating with the import command
 [[#Reverting to the latest vendor release|&bull; Reverting local changes]]::     Reverting to the latest vendor release
 [[#How to handle binary files with cvs import|&bull; Binary files in imports]]::     Binary files require special handling
 [[#How to handle keyword substitution with cvs import|&bull; Keywords in imports]]::         Keyword substitution might be undesirable
 [[#Multiple vendor branches|&bull; Multiple vendor branches]]::    What if you get sources from several places?
</div>


----

<div id="First-import"></div>
<div class="header">
<p>
Next: [[#Updating with the import command|Update imports]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Importing-for-the-first-time"></div>
=== Importing for the first time ===
<div id="index-Importing-modules"></div>

Use the <code>import</code> command to check in the sources
for the first time.  When you use the <code>import</code>
command to track third-party sources, the <em>vendor
tag</em> and <em>release tags</em> are useful.  The
<em>vendor tag</em> is a symbolic name for the branch
(which is always 1.1.1, unless you use the &lsquo;<code>-b
<var>branch</var></code>&rsquo; flag&mdash;see [[#Multiple vendor branches|Multiple vendor branches]].).  The
<em>release tags</em> are symbolic names for a particular
release, such as &lsquo;<code>FSF_0_04</code>&rsquo;.

Note that <code>import</code> does ''not'' change the
directory in which you invoke it.  In particular, it
does not set up that directory as a <small>CVS</small> working
directory; if you want to work with the sources import
them first and then check them out into a different
directory (see [[cvs: Overview#Getting the source|Getting the source]]).

<div id="index-wdiff-_0028import-example_0029"></div>
Suppose you have the sources to a program called
<code>wdiff</code> in a directory &lsquo;<tt>wdiff-0.04</tt>&rsquo;,
and are going to make private modifications that you
want to be able to use even when new releases are made
in the future.  You start by importing the source to
your repository:

<div class="example" style="margin-left: 3.2em">
 $ cd wdiff-0.04
 $ cvs import -m &quot;Import of FSF v. 0.04&quot; fsf/wdiff FSF_DIST WDIFF_0_04
</div>

The vendor tag is named &lsquo;<code>FSF_DIST</code>&rsquo; in the above
example, and the only release tag assigned is
&lsquo;<code>WDIFF_0_04</code>&rsquo;.


----

<div id="Update-imports"></div>
<div class="header">
<p>
Next: [[#Reverting to the latest vendor release|Reverting local changes]], Previous: [[#Importing for the first time|First import]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Updating-with-the-import-command"></div>
=== Updating with the import command ===

When a new release of the source arrives, you import it into the
repository with the same <code>import</code> command that you used to set up
the repository in the first place.  The only difference is that you
specify a different release tag this time:

<div class="example" style="margin-left: 3.2em">
 $ tar xfz wdiff-0.05.tar.gz
 $ cd wdiff-0.05
 $ cvs import -m &quot;Import of FSF v. 0.05&quot; fsf/wdiff FSF_DIST WDIFF_0_05
</div>

For files that have not been modified locally, the newly created
revision becomes the head revision.  If you have made local
changes, <code>import</code> will warn you that you must merge the changes
into the main trunk, and tell you to use &lsquo;<code>checkout -j</code>&rsquo; to do so:

<div class="example" style="margin-left: 3.2em">
 $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
</div>

The above command will check out the latest revision of
&lsquo;<code>wdiff</code>&rsquo;, merging the changes made on the vendor branch &lsquo;<code>FSF_DIST</code>&rsquo;
since yesterday into the working copy.  If any conflicts arise during
the merge they should be resolved in the normal way (see [[cvs: Multiple developers#Conflicts example|Conflicts example]]).  Then, the modified files may be committed.

However, it is much better to use the two release tags rather than using
a date on the branch as suggested above:

<div class="example" style="margin-left: 3.2em">
 $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
</div>

The reason this is better is that
using a date, as suggested above, assumes that you do
not import more than one release of a product per day.
More importantly, using the release tags allows <small>CVS</small> to detect files
that were removed between the two vendor releases and mark them for
removal.  Since <code>import</code> has no way to detect removed files, you
should do a merge like this even if <code>import</code> doesn&rsquo;t tell you to.


----

<div id="Reverting-local-changes"></div>
<div class="header">
<p>
Next: [[#How to handle binary files with cvs import|Binary files in imports]], Previous: [[#Updating with the import command|Update imports]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Reverting-to-the-latest-vendor-release"></div>
=== Reverting to the latest vendor release ===

You can also revert local changes completely and return
to the latest vendor release by changing the &lsquo;head&rsquo;
revision back to the vendor branch on all files.  For
example, if you have a checked-out copy of the sources
in &lsquo;<tt>~/work.d/wdiff</tt>&rsquo;, and you want to revert to the
vendor&rsquo;s version for all the files in that directory,
you would type:

<div class="example" style="margin-left: 3.2em">
 $ cd ~/work.d/wdiff
 $ cvs admin -bWDIFF .
</div>

You must specify the &lsquo;<code>-bWDIFF</code>&rsquo; without any space
after the &lsquo;<code>-b</code>&rsquo;.  See [[cvs: Guide to CVS commands#admin options|admin options]].


----

<div id="Binary-files-in-imports"></div>
<div class="header">
<p>
Next: [[#How to handle keyword substitution with cvs import|Keywords in imports]], Previous: [[#Reverting to the latest vendor release|Reverting local changes]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="How-to-handle-binary-files-with-cvs-import"></div>
=== How to handle binary files with cvs import ===

Use the &lsquo;<code>-k</code>&rsquo; wrapper option to tell import which
files are binary.  See [[cvs: Reference manual for Administrative files#The cvswrappers file|Wrappers]].


----

<div id="Keywords-in-imports"></div>
<div class="header">
<p>
Next: [[#Multiple vendor branches|Multiple vendor branches]], Previous: [[#How to handle binary files with cvs import|Binary files in imports]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="How-to-handle-keyword-substitution-with-cvs-import"></div>
=== How to handle keyword substitution with cvs import ===

The sources which you are importing may contain
keywords (see [[cvs: Keyword substitution#Keyword substitution|Keyword substitution]]).  For example,
the vendor may use <small>CVS</small> or some other system
which uses similar keyword expansion syntax.  If you
just import the files in the default fashion, then
the keyword expansions supplied by the vendor will
be replaced by keyword expansions supplied by your
own copy of <small>CVS</small>.  It may be more convenient to
maintain the expansions supplied by the vendor, so
that this information can supply information about
the sources that you imported from the vendor.

To maintain the keyword expansions supplied by the
vendor, supply the &lsquo;<code>-ko</code>&rsquo; option to <code>cvs
import</code> the first time you import the file.
This will turn off keyword expansion
for that file entirely, so if you want to be more
selective you&rsquo;ll have to think about what you want
and use the &lsquo;<code>-k</code>&rsquo; option to <code>cvs update</code> or
<code>cvs admin</code> as appropriate.


----

<div id="Multiple-vendor-branches"></div>
<div class="header">
<p>
Previous: [[#How to handle keyword substitution with cvs import|Keywords in imports]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
<div id="Multiple-vendor-branches-1"></div>
=== Multiple vendor branches ===

All the examples so far assume that there is only one
vendor from which you are getting sources.  In some
situations you might get sources from a variety of
places.  For example, suppose that you are dealing with
a project where many different people and teams are
modifying the software.  There are a variety of ways to
handle this, but in some cases you have a bunch of
source trees lying around and what you want to do more
than anything else is just to all put them in <small>CVS</small> so
that you at least have them in one place.

For handling situations in which there may be more than
one vendor, you may specify the &lsquo;<code>-b</code>&rsquo; option to
<code>cvs import</code>.  It takes as an argument the vendor
branch to import to.  The default is &lsquo;<code>-b 1.1.1</code>&rsquo;.

For example, suppose that there are two teams, the red
team and the blue team, that are sending you sources.
You want to import the red team&rsquo;s efforts to branch
1.1.1 and use the vendor tag RED.  You want to import
the blue team&rsquo;s efforts to branch 1.1.3 and use the
vendor tag BLUE.  So the commands you might use are:

<div class="example" style="margin-left: 3.2em">
 $ cvs import dir RED RED_1-0
 $ cvs import -b 1.1.3 dir BLUE BLUE_1-5
</div>

Note that if your vendor tag does not match your
&lsquo;<code>-b</code>&rsquo; option, <small>CVS</small> will not detect this case!  For
example,

<div class="example" style="margin-left: 3.2em">
 $ cvs import -b 1.1.3 dir RED RED_1-0
</div>

Be careful; this kind of mismatch is sure to sow
confusion or worse.  I can&rsquo;t think of a useful purpose
for the ability to specify a mismatch here, but if you
discover such a use, don&rsquo;t.  <small>CVS</small> is likely to make this
an error in some future release.



----

<div class="header">
<p>
Previous: [[#How to handle keyword substitution with cvs import|Keywords in imports]], Up: [[#Tracking third-party sources|Tracking sources]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
This document was generated on <i>a sunny day</i> using [http://www.nongnu.org/texi2html/ <i>texi2html</i>].
